[TDR Generic表][Java SDK]查询本地索引

1. 接口说明

根据部分Key字段值，从指定的表格中读取多条数据。

注意：按部分Key字段值读取数据之前，先要创建以对应键值为Key的索引，否则会报找不到索引的错误。

2. 版本要求

无特殊要求，所有版本都提供了该接口。

3. 准备工作

参见准备工作文档，完成使用该接口前的准备工作，并创建TDR Generic表。

准备工作完成后，将会获得以下信息，这些信息在使用SDK时会被用到：

目录服务器地址列表
业务ID
业务访问密码
游戏区ID
数据表名

4. 示例代码

示例代码的基本执行过程：

创建客户端；
构建请求；
发送请求；
处理响应；
销毁客户端。

4.1. 同步调用示例代码

import com.tencent.tcaplus.client.Client;
import com.tencent.tcaplus.client.ClientFactory;
import com.tencent.tcaplus.client.Record;
import com.tencent.tcaplus.client.Request;
import com.tencent.tcaplus.client.Response;
import com.tencent.tdr.tcaplus_protocol_cs.TcaplusProtocolCsConstants;

import java.util.ArrayList;
import java.util.List;

public class Example {

    public static void main(String[] arguments) {
        // 1. 准备环境信息
        // 1.1. 目录服务地址列表
        List<String> dirList = new ArrayList<String>();
        dirList.add("tcp://x.x.x.x:9999");
        dirList.add("tcp://y.y.y.y:9999");
        // 1.2. 业务ID
        int appId = 1;
        // 1.3. 业务密码
        String appPassword = "****************";
        // 1.4. 表格组ID
        int tableGroupId = 1;
        // 1.5. 表格名称
        String tableName = "test";

        // 2. 创建客户端
        Client client = ClientFactory.createClient(appId, tableGroupId, appPassword, dirList);
        try {
            // 3. 构造根据部分Key字段值读取数据的请求
            // 3.1. 获取请求对象。为了提升SDK性能，Request对象是复用的
            Request request = client.acquireRequest();
            // 3.2. 设置请求类型和目标表名
            request.setCmd(TcaplusProtocolCsConstants.TCAPLUS_CMD_GET_BY_PARTKEY_REQ);
            request.setTableName(tableName);
            // 3.3. 设置部分Key字段的值。本例中完整的Key由3个字段构成，但查询的时候只指定其中一个字段
            Record record = request.addRecord();
            record.setKeyInt("gameid", 1);
            // 3.4. 添加需要读取的Value字段
            request.addFieldName("typeid");
            request.addFieldName("Data");
            request.addFieldName("uname");
            // 3.5. 设置只返回结果列表中从offset开始的number个数据，不设置即返回所有满足条件的数据
            int offset = 0;
            int number = 100;
            request.setPartkeyGetParam(offset, number);

            // 4. 发送请求，并获取结果
            Response response = client.poll(request);

            // 5. 处理结果
            if (response.getResult() == 0) {
                // 读取数据成功
                Record result;
                while ((result = response.fetchRecord()) != null) {
                    // TODO 可在此处添加数据读取成功的后续处理代码
                }
            } else {
                // 读取数据失败
                // TODO 可在此处添加数据读取失败的后续处理代码
            }
        } finally {
            // 6. 销毁客户端对象
            ClientFactory.destroyClient(client);
        }
    }

}

4.2. 异步调用示例代码

import com.tencent.tcaplus.client.Client;
import com.tencent.tcaplus.client.ClientFactory;
import com.tencent.tcaplus.client.Record;
import com.tencent.tcaplus.client.Request;
import com.tencent.tcaplus.client.Response;
import com.tencent.tdr.tcaplus_protocol_cs.TcaplusProtocolCsConstants;

import java.util.ArrayList;
import java.util.List;

public class Example {

    public static void main(String[] arguments) {
        // 1. 准备环境信息
        // 1.1. 目录服务地址列表
        List<String> dirList = new ArrayList<String>();
        dirList.add("tcp://x.x.x.x:9999");
        dirList.add("tcp://y.y.y.y:9999");
        // 1.2. 业务ID
        int appId = 1;
        // 1.3. 业务密码
        String appPassword = "****************";
        // 1.4. 表格组ID
        int tableGroupId = 1;
        // 1.5. 表格名称
        String tableName = "test";

        // 2. 创建客户端
        Client client = ClientFactory.createClient(appId, tableGroupId, appPassword, dirList);
        try {
            // 3. 构造根据部分Key字段值读取数据的请求
            // 3.1. 获取请求对象。为了提升SDK性能，Request对象是复用的
            Request request = client.acquireRequest();
            // 3.2. 设置请求类型和目标表名
            request.setCmd(TcaplusProtocolCsConstants.TCAPLUS_CMD_GET_BY_PARTKEY_REQ);
            request.setTableName(tableName);
            // 3.3. 设置部分Key字段的值。本例中完整的Key由3个字段构成，但查询的时候只指定其中一个字段
            Record record = request.addRecord();
            record.setKeyInt("gameid", 1);
            // 3.4. 添加需要读取的Value字段
            request.addFieldName("typeid");
            request.addFieldName("Data");
            request.addFieldName("uname");
            // 3.5. 设置只返回结果列表中从offset开始的number个数据，不设置即返回所有满足条件的数据
            int offset = 0;
            int number = 100;
            request.setPartkeyGetParam(offset, number);

            CountDownLatch latch = new CountDownLatch(1);

            // 4. 异步发送请求，并指定返回结果处理器，post方法会立即返回
            client.post(request, new Future() {

                @Override
                public void onResponse(Response response) {
                    // 5. 处理响应
                    if (response.getResult() == 0) {
                        // 查询数据成功
                        // TODO 可在此处添加数据查询成功的后续处理代码
                    } else {
                        // 查询数据失败
                        // TODO 可在此处添加数据查询失败的后续处理代码
                    }
                }

            });

            latch.await();
        } finally {
            // 6. 销毁客户端对象
            ClientFactory.destroyClient(client);
        }
    }

}

5. 请求对象中的方法说明

注：如有未列出来的Request对象方法，即表示该方法在根据部分Key字段值读取数据的场景下是无效的。

方法签名	方法说明
`void setCmd(int cmd)`	设置请求类型（指令）。cmd：请求类型，固定为TcaplusProtocolCsConstants.TCAPLUS_CMD_GET_BY_PARTKEY_REQ。
`void setTableName(String tableName)`	设置目标表名。tableName：目标表名，不能为null。
`Record addRecord()`	获取数据对象（Record），用于设置读取的数据的Key，用户可以调用该对象的setKeyXXX方法设置各Key字段的值。
`void addFieldName(String fieldName)`	添加需要查询的数据的Value字段的名称。fieldName：Value字段名，不能为null。
`void setPartkeyGetParam(int offset, int num)`	设置只返回结果列表中从offset开始的number个数据，不设置即返回所有满足条件的数据。offset：起始位置。num：返回的最大数据个数。

5.1. 请求数据对象中的方法说明

注：如有未列出来的Record对象方法，即表示该方法在根据部分Key字段值读取数据的场景下是无效的。

方法签名	方法说明
`void setVersion(int version)`	设置数据的版本号。version：如果设置为负数，表示当前数据不启动版本控制。
`void setKeyByte(String fieldName, byte value)`	设置指定名称的Key字段的值。注意：当TDR表描述文件中定义的字段类型与Java的byte类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会参数错误。参见TDR表字段类型与Java类型对应关系。fieldName：字段名称，不可为null。value：字段的新值。
`void setKeyShort(String fieldName, short value)`	设置指定名称的Key字段的值。注意：当TDR表描述文件中定义的字段类型与Java的short类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会参数错误。参见TDR表字段类型与Java类型对应关系。fieldName：字段名称，不可为null。value：字段的新值。
`void setKeyInt(String fieldName, int value)`	设置指定名称的Key字段的值。注意：当TDR表描述文件中定义的字段类型与Java的int类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会参数错误。参见TDR表字段类型与Java类型对应关系。fieldName：字段名称，不可为null。value：字段的新值。
`void setKeyLong(String fieldName, long value)`	设置指定名称的Key字段的值。注意：当TDR表描述文件中定义的字段类型与Java的long类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会参数错误。参见TDR表字段类型与Java类型对应关系。fieldName：字段名称，不可为null。value：字段的新值。
`void setKeyFloat(String fieldName, float value)`	设置指定名称的Key字段的值。注意：当TDR表描述文件中定义的字段类型与Java的float类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会参数错误。参见TDR表字段类型与Java类型对应关系。fieldName：字段名称，不可为null。value：字段的新值。
`void setKeyDouble(String fieldName, double value)`	设置指定名称的Key字段的值。注意：当TDR表描述文件中定义的字段类型与Java的double类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会参数错误。参见TDR表字段类型与Java类型对应关系。fieldName：字段名称，不可为null。value：字段的新值。
`void setKeyString(String fieldName, String value)`	设置指定名称的Key字段的值。注意：当TDR表描述文件中定义的字段类型与Java的String类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会参数错误。参见TDR表字段类型与Java类型对应关系。fieldName：字段名称，不可为null。value：字段的新值。
`void setKeyBlob(String fieldName, byte[] value)`	设置指定名称的Key字段的值。注意：当TDR表描述文件中定义的字段类型与Java的byte[]类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会参数错误。参见TDR表字段类型与Java类型对应关系。fieldName：字段名称，不可为null。value：字段的新值。

6. 响应对象中的方法说明

注：如有未列出来的Response对象方法，即表示该方法在根据部分Key字段值读取数据的场景下是无效的。

方法签名	方法说明
`int getResult()`	获取根据部分Key字段值读取数据请求的响应码。0表示操作成功。非0表示操作异常，常见的错误码有： 261：数据记录不存在。参见响应码含义说明。
`List<Record> getRecordList()`	获取读取返回的数据对象列表。用户可以调用该对象的getValueXXX方法获取各Value字段的值。

6.1. 响应数据对象中的方法说明

注：如有未列出来的Record对象方法，即表示该方法在根据部分Key字段值读取数据的场景下是无效的。

方法签名	方法说明
`int getVersion()`	获取数据的版本号。
`int getValueCount()`	获取数据的Value字段的个数。
`byte getValueByte(String fieldName)`	获取指定名称的Value字段的值。fieldName：字段名称，不可为null。
`short getValueShort(String fieldName)`	获取指定名称的Value字段的值。fieldName：字段名称，不可为null。
`int getValueInt(String fieldName)`	获取指定名称的Value字段的值。fieldName：字段名称，不可为null。
`long getValueLong(String fieldName)`	获取指定名称的Value字段的值。fieldName：字段名称，不可为null。
`float getValueFloat(String fieldName)`	获取指定名称的Value字段的值。fieldName：字段名称，不可为null。
`double getValueDouble(String fieldName)`	获取指定名称的Value字段的值。fieldName：字段名称，不可为null。
`String getValueString(String fieldName)`	获取指定名称的Value字段的值。fieldName：字段名称，不可为null。
`byte[] getValueBlob(String fieldName)`	获取指定名称的Value字段的值。fieldName：字段名称，不可为null。